/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the 'License');
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { Location, PropType } from '~/type/Generic';
import { EngineCapabilityHint } from '~/extensions/hint/CapabilityHint';

/**
 * The final representation of a rule written in DSL.
 *
 * This is for the DSL adapter to translate the DSL rule to the engine's native rule.
 *
 * @typeParam T The concrete checker/rule type.
 *
 * @category Adapter
 */
export type DslRule<T = any> = (capability: EngineCapability) => T;

/**
 * Capability of the underlying linter engine.
 *
 * For specific types, refer to the docs of the engine.
 *
 * @typeParam T Type of extra capabilities.
 *
 * @category Adapter
 */
export interface EngineCapability<Hint extends EngineCapabilityHint = EngineCapabilityHint> {
    /**
     * Name of the engine.
     */
    name: string;

    /**
     * Global configuration of the engine.
     */
    config: PropType<Hint, 'config'>;

    api: {
        /**
         * Get the location of a node.
         *
         * @param node The node to get the location of.
         */
        getLocation(node: PropType<Hint, 'node'>): Location;

        /**
         * Report an issue.
         *
         * @param issue The issue to report.
         */
        report(issue: PropType<Hint, 'issue'>): void;
    };

    /**
     * Extra capabilities provided by the native engine, if any.
     */
    native: PropType<Hint, 'native'>;
}
